/*
 * Copyright 2002-2016 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.format;

import java.text.ParseException;
import java.util.Locale;

/**
 * <p>
 * 1. Parser
 *		功能
 * 			字符串到对象的解析：Parser<T> 接口定义了一个方法 T parse(String text, Locale locale)，它将给定的字符串解析为指定类型的对象实例。
 * 			这个接口主要用于从文本输入（如用户输入或配置文件）创建复杂的对象。
 *
 * 		使用场景
 * 			命令行参数解析：将命令行提供的字符串参数转换成应用程序所需的复杂对象。
 * 			配置文件解析：从属性文件或其他配置源读取字符串形式的数据，并将其转换为目标类型。
 *
 * 2. Printer
 * 	功能
 * 		对象到字符串的格式化：Printer<T> 接口包含一个方法 String print(T object, Locale locale)，它负责将给定的对象实例格式化为字符串表示。
 * 		与 Parser 相对，Printer 主要用于输出操作。
 *	使用场景
 * 		日志记录：将复杂对象转换为字符串以便记录到日志文件中。
 * 		视图渲染：在 Web 应用程序中，将模型中的对象转换为适合显示的字符串格式。
 *
 * 3. Converter
 * 	功能
 * 		简单类型之间的转换：Converter<S, T> 接口提供了一个方法 T convert(S source)，它可以将一种类型的对象转换为另一种类型。
 * 		这个接口适用于简单的、一对一的类型转换。
 *
 * 	使用场景
 * 		基本类型转换：例如，将 String 转换为 Integer 或者反之。
 * 		自定义类型转换：实现特定业务逻辑所需的数据类型转换。
 *
 * 4. GenericConverter
 * 	功能
 * 		复杂类型之间的转换：GenericConverter 接口扩展了 Converter 的概念，允许更灵活的多对多类型转换。
 * 		它通过 Set<ConvertiblePair> 来声明支持的源类型和目标类型组合，并且可以处理嵌套结构或集合类型的转换。
 *
 *	使用场景
 * 		复合类型转换：当需要在一个转换过程中涉及多个不同类型时，比如将 Map<String, Object> 转换为自定义对象。
 * 		集合转换：能够处理列表、集合等容器类型的元素转换。
 *
 *  示例代码
 * 		 public class MapToBeanConverter implements GenericConverter {
 *    		 private final Class<?> beanClass;
 *     		 public MapToBeanConverter(Class<?> beanClass) {
 *         		this.beanClass = beanClass;
 *     		}
 *     		@Override
 *     		public Set<ConvertiblePair> getConvertibleTypes() {
 *         		return Collections.singleton(new ConvertiblePair(Map.class, beanClass));
 *     		}
 *     		@Override
 *     		public Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType) {
 *       		  Map<String, ?> map = (Map<String, ?>) source;
 *        		 // 实现从 Map 到 Bean 的转换逻辑
 *         		return BeanUtils.instantiateClass(beanClass);
 *     		}
 * 		}
 *
 *
 * </p>
 * Parses text strings to produce instances of T.
 * <br> 解析 文本字符串以产生T的实例。
 *
 * @author Keith Donald
 * @since 3.0
 * @param <T> the type of object this Parser produces
 */
@FunctionalInterface
public interface Parser<T> {

	/**
	 * Parse a text String to produce a T.
	 * @param text the text string
	 * @param locale the current user locale
	 * @return an instance of T
	 * @throws ParseException when a parse exception occurs in a java.text parsing library
	 * @throws IllegalArgumentException when a parse exception occurs
	 */
	T parse(String text, Locale locale) throws ParseException;

}
